Skip to content

WIP feat(gnoweb): add State Explorer for browsing on-chain realm state#5283

Open
jaekwon wants to merge 5 commits intofeat/jae/json-vm-specs3from
feat/jae/state-explorer
Open

WIP feat(gnoweb): add State Explorer for browsing on-chain realm state#5283
jaekwon wants to merge 5 commits intofeat/jae/json-vm-specs3from
feat/jae/state-explorer

Conversation

@jaekwon
Copy link
Contributor

@jaekwon jaekwon commented Mar 13, 2026 •
edited
Loading

Summary

  • Add a State Explorer tab to gnoweb that renders persisted realm/package state as an interactive, expandable
    tree
  • Add VM query endpoints (vm/qpkg_json, vm/qobject_json, vm/qtype_json) that export Amino JSON for package
    variables, objects by ObjectID, and types by TypeID
  • Add @gnojs/amino TypeScript library (misc/gnojs/) that decodes Amino JSON wire format into UI-friendly
    StateNode trees
  • Support lazy-loading of persisted objects, struct field name resolution, closure capture display, function source
    locations, and OID navigation from the searchbar
  • Depends on refactor(vm): replace custom JSON types with standard Amino encoding (alternative to #4972) #5274

Architecture

Three layers:

  1. VM endpoints — qpkg_json, qobject_json, qtype_json return raw Amino JSON
  2. @gnojs/amino — TypeScript decoder producing StateNode trees (handles primitives, structs, maps,
    pointers, refs, closures, heap items, cycles)
  3. gnoweb controller — renders interactive HTML with expand/collapse, color-coded types, lazy fetch, and source
    code display

See ADR-003 for full design details.

Key files

  • gno.land/pkg/sdk/vm/keeper.go — QueryPkgJSON, QueryObjectJSON, QueryTypeJSON
  • gno.land/pkg/sdk/vm/handler.go — route registration
  • gnovm/pkg/gnolang/values_export.go — Amino JSON export for GnoVM values
  • misc/gnojs/src/decode.ts — Amino JSON → StateNode decoder
  • gno.land/pkg/gnoweb/handler_http.go — GetStateView, ServeStateJSON
  • gno.land/pkg/gnoweb/frontend/js/controller-state-explorer.ts — tree UI controller

Follow-up PR

  • known types like AVL (perhaps those that implement select known interfaces?) should have an alternative view that just shows the leaf values.

Test plan

  • go test ./gno.land/pkg/sdk/vm/... — keeper and handler tests for all three query endpoints
  • go test ./gno.land/pkg/gnoweb/... — HTTP handler tests for state view and JSON API
  • npx tsx misc/gnojs/src/decode.test.ts — TypeScript decoder tests (primitives, structs, maps, pointers,
    funcs, closures)
  • Manual: run gnodev examples/gno.land/r/demo/boards, navigate to State tab, expand objects
  • Manual: test closure display with r/demo/closuretest

🤖 Generated with Claude Code

@jaekwon jaekwon requested review from alexiscolin and moul March 13, 2026 07:20
@github-actions github-actions bot added 📖 documentation Improvements or additions to documentation 🧾 package/realm Tag used for new Realms or Packages. 📦 🤖 gnovm Issues or PRs gnovm related 📦 ⛰️ gno.land Issues or PRs gno.land package related 🌍 gnoweb Issues & PRs related to gnoweb and render 🛠️ gnodev labels Mar 13, 2026
@Gno2D2 Gno2D2 requested a review from gfanton March 13, 2026 07:21
@Gno2D2
Copy link
Collaborator

Gno2D2 commented Mar 13, 2026 •
edited
Loading

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):
  • IGNORE the bot requirements for this PR (force green CI check)
Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

No automated checks match this pull request.

☑️ Contributor Actions:
  1. Fix any issues flagged by automated checks.
  2. Follow the Contributor Checklist to ensure your PR is ready for review.
    • Add new tests, or document why they are unnecessary.
    • Provide clear examples/screenshots, if necessary.
    • Update documentation, if required.
    • Ensure no breaking changes, or include BREAKING CHANGE notes.
    • Link related issues/PRs, where applicable.
☑️ Reviewer Actions:
  1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.
📚 Resources:
Debug
Manual Checks
**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

  • Any user with comment edit permission

@jaekwon jaekwon changed the base branch from master to feat/jae/json-vm-specs3 March 13, 2026 07:22
@codecov
Copy link

codecov bot commented Mar 13, 2026 •
edited
Loading

Codecov Report

❌ Patch coverage is 48.94366% with 145 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
gno.land/pkg/sdk/vm/keeper.go 52.58% 47 Missing and 8 partials ⚠️
gno.land/pkg/gnoweb/handler_http.go 47.16% 26 Missing and 2 partials ⚠️
gno.land/pkg/sdk/vm/handler.go 0.00% 24 Missing ⚠️
contribs/gnodev/pkg/proxy/path_interceptor.go 57.40% 19 Missing and 4 partials ⚠️
gno.land/pkg/gnoweb/client.go 0.00% 11 Missing ⚠️
gno.land/pkg/gnoweb/client_mock.go 55.55% 4 Missing ⚠️

📢 Thoughts on this report? Let us know!

jaekwon and others added 5 commits March 13, 2026 00:31
@jaekwon @claude
fix(gnodev): rewrite lazy loading proxy as HTTP reverse proxy
efc0917 
The TCP proxy maintained a persistent connection to the node's RPC server.
When a PathHandler triggered a node reload (stop + restart), that connection
died, causing the query that triggered the reload to silently fail.

Replace the TCP-level proxy with an HTTP reverse proxy (httputil.ReverseProxy)
so each request gets a fresh connection. The handler runs synchronously before
forwarding, so after a reload the request naturally connects to the new node.

Disable keep-alive on the transport to prevent stale pooled connections after
restarts. Add TestProxyRestart to validate queries succeed across node restarts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jaekwon @claude
feat(gnoweb): add state explorer with qpkg_json/qtype_json endpoints
9a5ac64 
Add an interactive state explorer to gnoweb that lets users browse
on-chain package state as a lazy-loaded tree. Introduces two new VM
query endpoints (qpkg_json for package variables, qtype_json for type
definitions) alongside the existing qobject_json, all using standard
Amino JSON encoding.

Includes @gnojs/amino (misc/gnojs), a standalone TypeScript library
for decoding Amino JSON into navigable StateNode trees, and wires it
into gnoweb's frontend controller for tree rendering with expand/collapse.

Also adds documentation for the JSON query API and updates gnodev's
proxy interceptor to handle the new endpoints for lazy loading.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jaekwon @claude
fix(gnoweb): fix state explorer layout and JSON encoding
2f00a46 
- Use template.JS for NodesJSON to prevent double-encoding in <script> tags
- Add grid-column: 1/-1 so state explorer spans the full grid width
- Simplify header: remove redundant h1 and pkg path (tab already labels the view)
- Add white-space: nowrap on count text

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jaekwon @claude
feat(gnoweb): polish state explorer UI - tabs, colors, source links, …
b644529 
…OID search

Add State as top-level navigation tab alongside Content, Source, and Actions.
Restore colorful type annotations by fixing PurgeCSS deep safelist for dynamic
b-state-kind-- classes. Move function source links to top-right corner of code
boxes. Add OID pattern detection in searchbar for direct object navigation.
Match State view spacing/footer behavior with Content view. Add closuretest
demo realm for testing closure variable captures.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jaekwon @claude
feat(gnoweb): closure captures, tests, and ADR for state explorer
2b0ae08 
Add closure support to the state explorer: detect closures via non-empty
Captures array in FuncValue, display captured variables as expandable
children with "Captured variables:" label, and use blue color (info) to
distinguish closures from regular functions (purple/tip).

Add integration tests for state explorer HTTP endpoints (state view,
state JSON API for pkg/oid/tid) and decoder tests for funcs, closures,
and multi-capture scenarios. Fix existing layout tests to expect the
new State tab.

Add ADR-003 documenting the state explorer architecture, and update
the @gnojs/amino README with closure/captures documentation.

Also fix Makefile to track misc/gnojs/src as esbuild dependency.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@jaekwon jaekwon force-pushed the feat/jae/state-explorer branch from 2bbc595 to 2b0ae08 Compare March 13, 2026 07:36
@jaekwon jaekwon mentioned this pull request Mar 13, 2026
Open
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@moul moul Awaiting requested review from moul

@alexiscolin alexiscolin Awaiting requested review from alexiscolin

@gfanton gfanton Awaiting requested review from gfanton

Assignees

@jaekwon jaekwon

Labels

📖 documentation Improvements or additions to documentation 🛠️ gnodev 🌍 gnoweb Issues & PRs related to gnoweb and render 📦 ⛰️ gno.land Issues or PRs gno.land package related 📦 🤖 gnovm Issues or PRs gnovm related 🧾 package/realm Tag used for new Realms or Packages.

Projects

💪 Bounties & Worx
Status: No status
🧙‍♂️Gno.land development
Status: Triage

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jaekwon @Gno2D2